/*
 * Copyright (c) 2009, Katholieke Universiteit Leuven
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 * 
 *     * Redistributions of source code must retain the above copyright notice,
 *       this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright notice,
 *       this list of conditions and the following disclaimer in the documentation
 *       and/or other materials provided with the distribution.
 *     * Neither the name of the Katholieke Universiteit Leuven nor the names of
 *       its contributors may be used to endorse or promote products derived from
 *       this software without specific prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/**
 * @addtogroup net
 * @{
 *
 * @defgroup peers The LooCI peers library
 * @{
 *
 * This library is used to allow the LooCI system to store each peer address only once.
 * 
 * The peer address is typically a large data structure (16 bytes for uIP6). This library
 * allows to use an id, which is a lot smaller.
 */
/**
 * @file
 * The header file for the LooCI peers library
 * @author
 * Wouter Horré <wouter.horre@cs.kuleuven.be>
 */
#ifndef __PEERS_H__
#define __PEERS_H__

#include "contiki-net.h"

/**
 * The peer id that will never be assigned to a real peer.
 *
 * If this peer id is returned, it indicates a failure
 */
#define PEER_ID_NONE 0
/**
 * The peer id that will be assigned to the 'broadcast peer'.
 * In the current IPv6 implementation, this is the 
 * 'all nodes on this link' multicast address FF02::1
 */
#define PEER_ID_ALL 1

/**
 * The type of the peer id.
 */
typedef u8_t peer_id_t;
/**
 * The type of the peer address
 */
typedef uip_ip6addr_t peer_addr_t;

/**
 * Initialize the peer library
 */
CCIF void peer_init();

/**
 * Add a peer to the peer list
 *
 * @param addr The address of the new peer
 *
 * @return The id assigned to the peer
 */
CCIF peer_id_t peer_add(peer_addr_t * addr);

/**
 * Remove a peer from the peer list
 *
 * @param id The peer id
 *
 * @note All peer_addr_t pointers become invalid by calling this method.
 *       They must be rerequested from the peers library with a call to
 *       peer_get_addr().
 */
CCIF void peer_remove(peer_id_t id);

/**
 * Get the address of a peer
 *
 * @param id The peer id
 *
 * @return The address of the peer. NULL if the id is not known.
 *
 * @note The returned pointer is NOT valid across Contiki
 *       process waits!!!
 */
CCIF peer_addr_t * peer_get_addr(peer_id_t id);

/**
 * Get the id of a peer
 *
 * @param addr The address of the peer
 *
 * @return The id of the peer. PEER_ID_NONE if the peer isn't
 *         in the list yet.
 */
CCIF peer_id_t peer_get_id(peer_addr_t * addr);

/**
 * Get the id of a peer or add it if the peer is not yet known.
 *
 * @param addr The address of the peer
 *
 * @return The id of the peer.
 */
CCIF peer_id_t peer_get_id_or_add(peer_addr_t * addr);

#endif // __PEERS_H__
/** @} */
/** @} */
